/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			pgsqs.h
  \date			Feb 2012
  \author		TNick

  \brief		Contains the definition for PgsQs class


*//*


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please read COPYING and README files in root folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __PGSQS_INC__
#define __PGSQS_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<QSettings>

#ifdef	USE_PGSAVE_INTERFACE
#include	"ipgsave.h"
#endif

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */

namespace PgSave		{

/**
	@brief	Offers a consistent way of saving things using QSetings

	The class may be used as it is, without \b USE_PGSAVE_INTERFACE defined, or
	as a class exposing the IPgSave interface otherwise. The only major
	difference is that some methods are virtual when used with
	\b USE_PGSAVE_INTERFACE.
*/
class PgsQs
#ifdef	USE_PGSAVE_INTERFACE
:	public	IPgSave
#endif
{

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

#ifdef	PGSAVE_TESTS
	friend void		PgsQs_Tests	( int&, int& );
#endif

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

private:

	/**
	*	@brief	the settings object that we're wrapping here
	*/
	QSettings		stgs_;


	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */

public:


	/**
	*	@brief	constructor;
	*/
	PgsQs			( void );


	/**
	*	@brief	destructor;
	*/
	virtual				~PgsQs		( void );



	/**
	*	@brief	changes the current path in this instance
	*
	*	The path may be changed to an absolute path or provided path
	*	may be appended to current path. If the path starts with a "/" then
	*	the path is absolute, otherwise is relative.
	*
	*	Paths are sepparated by a "/" character despite the opperating system
	*	settings regardng paths.
	*
	*	@param	new_crt	string representing new path
	*/
	bool		setPath			(
			const QString			new_crt
			);


	/**
	*	@brief	retrieve current path as a list of names sepparated by "/"
	*/
	QString		path			( void );


	/**
	*	@brief	retrieve current path as a list of strings
	*
	*	@param	sl_out list where the names are appended; it is not cleared;
	*/
	void		path			( QStringList & sl_out );


	/**
	*	@brief	walks up specified number of steps in the path
	*
	*	If the path is already at the root nothing happens. If the number of
	*	steps are larger than the number of steps to the root the root is set.
	*/
	void		cdUp			( unsigned steps = 1 );


	/**
	*	@brief	tells if the path exists or not
	*
	*	If the path starts with a "/" then the path is absolute,
	*	otherwise is relative.
	*
	*	The method will return false for paths that are only folders
	*	without holding an actual value.
	*
	*	@param	s_path	string representing the path to test
	*/
	bool		exists			( QString s_path );


	/**
	*	@brief	iterates the values in current path
	*
	*	The method uses the callback list to find the proper one to call.
	*	If there is no callback for a particular type the default callback
	*	provided as an argument will be used, except if it is NULL, when they
	*	simply ignored.
	*
	*/
	 void		blindLoad		(
			 KB_BLIND_LOAD		kb_default = NULL,
			 void *				kb_data = NULL
			 );


	 /**
	 *	@brief	iterates the provided strings and loads the ones it finds
	 *
	 *	The method uses the callback list to find the proper one to call.
	 *	If there is no callback for a particular type the default callback
	 *	provided as an argument will be used, except if it is NULL, when they
	 *	simply ignored.
	 *
	 */
	  void		blindLoad		(
			  QStringList			load_list,
			  KB_BLIND_LOAD			kb_default = NULL,
			  void *				kb_data = NULL
			  );

	/** @name Retrieving common values
	*
	*/
	//@{

	bool			getBool		(
			QString		s_name,
			bool *		b_ok
			);

	qint16			getShort		(
			QString		s_name,
			bool *		b_ok
			);

	qint32			getInt		(
			QString		s_name,
			bool *		b_ok
			);

	qint64			getLong		(
			QString		s_name,
			bool *		b_ok
			);

	qint8			getByte		(
			QString		s_name,
			bool *		b_ok
			);

	QColor			getColor	(
			QString		s_name,
			bool *		b_ok
			);

	qreal			getDouble	(
			QString		s_name,
			bool *		b_ok
			);

	QStringList		getStrLst	(
			QString		s_name,
			bool *		b_ok
			);

	QString			getStr		(
			QString		s_name,
			bool *		b_ok
			);

	//@}



	//@{
	//!	change the value of the variable; this is a top level method
	//!
	//!	The methods call the validators if present and informs the callbacks

	bool		set		(
			QString			s_name,
			const qint64	new_val
			);

	bool		set		(
			QString			s_name,
			const int		new_val
			);

	bool		set		(
			QString			s_name,
			const bool		new_val
			);

	bool		set		(
			QString			s_name,
			const char		new_val
			);

	bool		set		(
			QString			s_name,
			const QRgb		new_val
			);

	bool		set		(
			QString			s_name,
			const QColor	new_val
			);

	bool		set		(
			QString			s_name,
			const QString	new_val
			);

	bool		set		(
			QString			s_name,
			const char *	new_val
			);

	bool		set		(
			QString			s_name,
			const qreal		new_val
			);

	//@}

	/* ----------------------------------------------- */
	/* methods below this line are not part of IPgSave */
	/* ----------------------------------------------- */


	/**
	*	@brief	creates a new instance and sets current path at
	*	provided location
	*/
	static PgsQs *		create		(
			QString								s_path
			);


	/**
	*	@brief	creates a new instance and sets current path at
	*	provided location
	*/
	static PgsQs *		create		(
			QString								s_path,
			QMap<QString, KB_BLIND_LOAD>	&	other_map
			);

	/**
	*	@brief	allows direct access to QSettings inside
	*/
	inline QSettings *			impl		( void )
	{ return &stgs_; }


	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class PgsQs	*/

/*  CLASS    =============================================================== */
//
//
//
//

#ifdef	PGSAVE_TESTS
	void		PgsQs_Tests	( int&, int& );
#endif

}	//	namespace PgSave

#endif // __PGSQS_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
